feat: spark emergency exit - #1217

Closes #1242
Closes #1296
Twin: synonymdev/bitkit-android#1782
Stacked on #1128

This PR adds Emergency exit, Spark's unilateral exit: if the Spark operators stop working, Spending moves to Savings on-chain without them. It builds on the Spark wallet in #1128, which already backs up Spark's exit data to VSS as SPARK_EXIT.

Description

What this PR does

• Lightning Connections › Spark shows Emergency exit while Spark holds funds. It opens an explainer, a quote (amount, fees, what arrives, what stays on Spark), fee funding, a confirm swipe, progress and the result.
• Fee funding is paid from Savings, or sent from another wallet to a shown address.
• Progress shows the steps and the timelock countdown, asks for more fees when needed, and offers Pay a higher fee when the network outbids the exit.
• If the Savings payment is refused, Progress says "Your savings payment didn't go through. Pay again, or fund from another wallet." and offers Pay from savings again.
• The exit runs in the background with Bitkit closed and notifies only when it needs you. It can take up to 4 weeks.
• When it ends, leftover fee funding goes back to Savings, and the result shows what reached Savings and what stayed on Spark.
• A restored wallet keeps watching earlier exits' funding. The next funding index and the earlier exit addresses are in the VSS backup. After a restore from a backup without them, Bitkit scans the funding addresses (gap of 20, at most 1,000) and watches any that still hold coins.
• The exit's strings are in English; translations follow in chore: translate spark strings #1270.

Decisions for review

• Trust. The exit needs no operator: the app signs and broadcasts every step itself. On mainnet it reads the chain only from https://bitkit.to/electrs and broadcasts there first, with mempool.space and blockstream.info as fallbacks.
• Funding key. The CPFP fees come from a key on its own account (m/84'/{coin}'/7797'/0/<index>, a fresh index per exit), so ldk-node never spends the exit's funding.
• Fee funding. Savings or another wallet pays one amount, which the SDK splits into one output per step, so a lost fee race strands one step instead of the chain after it. A top-up asks only for what is still missing, at least the 294-sat dust limit.
• Refused Savings payment. Pay from savings re-signs the same payment over the inputs it already spends, so at most one version can confirm. Cancel waits for it and keeps the exit.
• Spark during an exit. No Lightning sends or receives on Spark, and leaf optimization stays off so no swap hands away an exiting leaf. The balance shows as in transfer to Savings on Home and Savings. Cancel works only while nothing was paid; funding already at the address goes back to Savings.
• Saved before sent. Every build is saved before broadcast and every broadcast is saved as it is answered, so a killed run never sends a step twice.
• Stalls. A broken fee chain rebuilds the exit; after 3 rebuilds with nothing confirming, Progress says it is not moving. A step that is only underpriced is not rebuilt; Progress offers Pay a higher fee instead.
• What stays on Spark. Leaves too small to pay their own exit, and fee-ladder leaves that can't pay their refund, stay on Spark, and the quote says how much. A leaf an older owner already claimed on-chain is dropped and named on Progress.
• Leftover sweep. It pays the network's cheapest rate and waits up to about 4 weeks for fees to drop before keeping the change at the funding address, whose derivation path the result shows.
• Glow. Stall handling, waits for leaves that may still move, and top-up fees follow Breez's reference wallet, breez/glow-web. The lost fee race, lost leaves and background runs are our own handling, since Glow has none.

Background run on iOS

• A BGAppRefreshTask and a BGProcessingTask run the exit with Bitkit closed, when iOS grants them. Each run sends the signed steps, starts Spark alone (never ldk-node), and stops cleanly when the OS expires it.

Notifications on iOS

• Each run schedules reminders ahead, 12 blocks after each step matures, inside the operators' ~50-block window. A run that publishes the step removes its reminder.
• Needing more fees, an exit that is not moving, and a failed exit notify at once.

Out of Scope

• SPARK_EXIT exit data backup: in feat: add spark via breez sdk #1128.
• A savings retry from Progress after a start refused because the savings fee changed: bug: no savings retry after a refused exit start #1282.
• Translations of the new exit strings: chore: translate spark strings #1270.

Risks for review

• Mainnet. No exit has run on mainnet. Fee-ladder leaves and package relay at the three hosts are untested with a real exit. About 50 blocks (8 hours) after a step matures, the operators may publish their own version, paid from the leaf. iOS grants no background runs while Background App Refresh is off or Low Power Mode is on, and reminders need notification permission; Progress says so.
• Cost. At 2 sat/vB, leaves under about 4,096 sats cost more to exit than they hold, so a typical balance recovers about 75% after fees, in about 13 to 14 days. With healthy operators, Transfer to Savings stays the cheaper way out, and the explainer says so.

Design

N/A — no design available.

Preview

Emergency exit at 6818189 on an iPhone 17 Pro 2x simulator (iOS 27.0) in Bitkit's dark theme. Start and Fund from another wallet run live against Spark's hosted regtest with notifications denied; another wallet pays the fee funding in two parts, and the waits for the payments are cut. Pay from savings is the earlier recording from dfc1716 and predates this PR's latest UI fixes (its step icons and inline transaction ID are the old ones): Savings on the simulator runs on a separate regtest chain, so a savings payment can't be recorded again here. Running exit, Redo and sweep, and Exit complete are staged from saved exit records on a debug build, each state shown in turn; Done with the leftover swept is shown through a local hook that is not in this PR.

Screens

Every exit screen, at 6818189 on an iPhone 17 Pro 2x simulator (iOS 27.0) in Bitkit's dark theme. Start screens and the notification prompt are from the live exit above; Savings is empty there, so Funding choices shows Pay from savings as unavailable and Confirm follows Fund from another wallet. Progress and Result screens are staged from saved exit records on a debug build, with Needs funding, partial and Payment seen reading real payments on Spark's regtest chain. Done, leftover swept and the Pay a higher fee rates are shown through a local hook that is not in this PR; Pay a higher fee reads 0 sat/vB because the staged record saves no fee rate, and its speeds are unavailable because Savings is empty.

Start

Spark detail during an exit	Intro	Quote with the can't-exit note	Funding choices

Funding address	Partial payment hint	Notification permission	Confirm

Progress

Needs funding	Needs funding, partial	Paid from savings at 27b2ce1	Payment seen at 27b2ce1

Running, network fees rose	Pay a higher fee

Result

Leftover sending	Done, leftover swept	Stopped	Stopped, balance stays on Spark

Lost to an older owner

QA Notes

Setup

• Dev build (regtest) needs no key. Spark is funded from Lightspark's regtest faucet, sent to the deposit address on the Spark screen (Settings › Advanced › Lightning Connections › Spark). On dev, an exit's Pay from savings goes to Bitkit's staging chain and never confirms on Spark's; Fund from another wallet with the faucet does.
• A full exit needs a chain you can mine: Lightspark's hosted regtest takes the real CSV of about 1,900 blocks, and its faucet needs credentials only Breez's CI holds. The exit results below ran on a local Spark regtest stack built from spark-sdk's public regtest/local setup (the last public operator), with bitcoind, 3 operators, the SSP, electrs and mempool, mined on demand. Two patches make SDK 0.27.2 work with that operator: the operator skips the RETURNED status filter it does not know, and the wallet turns fee ladders off, so every leaf there is an anchored leaf.
• Besides the app, a small harness on SDK 0.27.2 made the same calls as the app's driver (prepareRecoverFunds with All, then Specific on a rebuild, recoverFunds with a single-key CPFP signer, checkRecoverFunds, package broadcast through mempool), each step a separate process resuming from storage.

Journeys

• J1: new journeys/transfer/spark-emergency-exit.xml — Emergency exit up to the swipe: explainer, quote, funding choices and the funding address, with nothing started (ported from feat: spark emergency exit bitkit-android#1782). Needs Spark's regtest faucet for the balance.

Manual Tests

• 1. Dev, Spark funded from the faucet, Settings › Advanced › Lightning Connections › Spark › Emergency exit → explainer, then the quote lists amount, network fees, You receive about, Fee funding needed and what stays on Spark — the faucet is outside the journey environment.
• 2. Dev, continue with Fund from another wallet, send the fee funding from the faucet to the shown address, swipe → progress shows the funding step done after 1 confirmation, then publishing, the timelock countdown and the sweep; the exit survives an app kill and continues on reopen — faucet and hours of regtest blocks.
• 4. Phone under Xcode, dev, an exit running: background Bitkit, pause in the debugger and run e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"to.bitkit.spark-exit"], continue → the log shows Spark exit background run: connected=true with the time per step; repeat with to.bitkit.spark-exit.processing, then once more followed by _simulateExpirationForTaskWithIdentifier: → the run stops, and the next run sends nothing already accepted. Turn Background App Refresh off for Bitkit → Progress shows the note; Low Power Mode on → its note — the simulator has no BGTaskScheduler.
• 5. Dev, Spark funded, Emergency exit with Pay from savings → Progress shows "Paid from savings, waiting for confirmation" with its transaction ID and no QR or ask; Cancel exit backs out — Spark's regtest is not in the journey environment.
• 6. Dev, Emergency exit with Fund from another wallet, pay the address from the faucet → Funding shows Payment seen, Progress shows "Payment seen, waiting for confirmation" with its transaction ID until it confirms, then publishing — faucet.
• 7. Local Spark regtest, an exit that ends after a Redo needing no funding → Emergency exit and the Spark row open the result with the leftover sweep sending, then sent with its transaction ID; a new intro shows only after it confirms — needs a chain you can mine.
• 8. Local Spark regtest, a second exit on the same wallet → its funding address differs from the first exit's — same.
• 9. Local Spark regtest, kill Bitkit while refunds wait for their timelock, mine to maturity and relaunch → nothing is sent before it matures, and non-BIP68-final never counts toward the 3-refusal alert — same.

Automated Checks

• SparkExitReviewTests covers cancel (off once paid or seen; funding at the address is swept back, an unreadable address keeps the exit), no height from a failed tip read, the live generation driven while a higher fee's top-up confirms, a dropped or stale savings payment brought back to an ask, a diverged rebuild's top-up sending nothing, the snapshot imported before fee-bump pricing, the reminder for an unfunded exit, fired reminders remembered, the sweep's bounded states, salvage keeping chained transactions, the connect timeout returning on time, cancel revalidating a built record, a confirmed partial sweep following what it left out, only-failed cooperative leaves waiting for the operators, fee-bump pricing past a refused leaf, per-exit reminder ids and the background chain's economy rate; SparkExitBackgroundRunTests covers a failed pass handing back the saved record.
• SparkExitReviewTests also covers a refused savings payment shown until a payment is kept, and paying again retrying only the refused attempt.
• Per-step funding, Pay a higher fee, retried leaves and the fee change sweep: unit tests in SparkExitFeeBumpTests and SparkExitSweepTests, plus dark-mode screens rendered with stubbed state by a local hook not in this PR. Not run on a live chain yet.
• added SparkExitTests.swift — the background entry point from a cold start sends stored steps and then checks with the SDK only, signs a build once funding confirmed, stays keyless when Spark does not connect or time is short, and after an expiry mid-broadcast leaves a whole record from which the next run sends nothing twice; reminders are planned at each unpublished timelock plus the grace, dropped once a step is published, sent at once for fee funding and repeated refusals, and after a stall while steps wait for parents; the record round-trips with every status, error and input variant; the recovery is written in spark-sdk's serde shape and a CLI-written one reads back; an unknown version is refused; the driver waits for a confirmed funding UTXO, saves before broadcasting, broadcasts ready steps once until due, finishes on Done with the leftover read, rebuilds a new generation on Redo after saving it, asks only for what the inputs lack on InsufficientCpfpFunds, adopts several small payments together and ignores CPFP change at the funding address, resumes after a restart without repeating broadcasts, retries cooperative leaves the operators could not sign, and broadcasts without the SDK only steps whose parents confirmed and timelocks matured; a leaf whose refund two rebuilds reproduce after its input was spent is lost, alone or with every leaf (the exit stops); a rebuild leaves behind a leaf that cannot pay its refund and retries, falls back to RecoverableOnly when the error names no leaf, and stops when none is left; the quote math, funding states, funding key path, the package and single broadcasts, path and host fallback, and the node answer classifier
• added SparkExitSweepTests.swift — the leftover sweep spends every UTXO at the funding address to Savings less its fee, each input's signature verifies against its BIP143 digest with libsecp256k1, a leftover under dust after the fee is skipped, output scripts for every address type, an ended exit keeps its result reachable until the sweep confirms, and a background run sweeps without starting Spark
• added SparkExitRegtestTests.swift — opt-in (TEST_RUNNER_SPARK_EXIT_REGTEST=1): a fresh wallet on Spark's hosted regtest connects and quotes an empty exit, the chain host serves the tip and funding UTXOs, a fake parent and child package reaches the live node and is read as retry later, and the background entry point runs from a cold start over an exit of the live run's shape
• SparkExitTests.swift also covers a fee chain that lost a race, with the operators down and the check answering Valid (rebuilt from the same funding, the dead chain never resent), a child still in the mempool, the safety net's rebuild, which never counts as a refusal, the chain host's not-found lookup, and the needs-funding amount never under the 294-sat dust limit, and a replay of a single-leaf exit an older state claimed, which across its rebuilds delivers only the lost notification
• SparkExitTests.swift also covers mainnet reading only from bitkit.to/electrs and broadcasting there first (packages on /txs/package) with mempool.space and blockstream.info as fallbacks, a transaction counted gone only on a 404 from the one read host (never on a 5xx or timeout), lost leaves from a stored record joining the lost-leaf list on load, ended exits included, and lost leaves kept out of the stays-on-Spark and can't-be-exited amounts whether the Spark balance still counts them or not
• Stalls, leaf waits, exit data, sweep replacement, salvage, countdown and top-ups, in SparkExitTests.swift, SparkExitSweepTests.swift and SparkExitBackupTests.swift:
  • refused steps rebuild 3 times while no step confirms, then the exit is not moving; a step confirming resets the count; a stalled-chain rebuild strikes no leaf;
  • an accepted step unconfirmed for over 6 blocks is underpriced and not rebuilt, and gets one reminder; a nonzero-fee refusal under the mempool's minimum (both node texts) shows the same at once without a rebuild, while a zero fee and a lost replacement race still rebuild; a step confirmed since is not stuck;
  • an unverified unilateral step is not sent and the exit rebuilds over it once a block; a ready step holds that rebuild, and a cooperative unverified step is still sent;
  • funds not found waits, retries after 6 blocks at doubling gaps up to 144, and lets go after 1,008; a stopped leaf waits 6 blocks, then is let go; a stopped leaf still waiting is never struck;
  • the exit data is exported once before the first build and imported before every rebuild; the SPARK_EXIT backup is not uploaded while an exit runs;
  • a sweep refused for its fee is rebuilt at the network's rate, one unconfirmed for 144 blocks is replaced, a replaced sweep confirming ends it, and a replacement that would be dust keeps the accepted sweep;
  • a record of an unknown version keeps its exit, with its funding and transfer, to rebuild from the chain; an ended or unusable one is not revived; one that cannot be read yet is left alone;
  • the countdown holds when a parent confirms; Done reads what reached savings, a cooperative recovery from before a Redo included, and the sweep's txid; each extra payment adds its 68 vB input fee, so the run's 8,541 + 4 × 136 matches the SDK's 9,085
• updated SparkConfigTests.swift — leaf optimization is on, and off while an exit runs
• ran the unit suite (CI's selection) on this head and on feat: add spark via breez sdk #1128's head; SwiftFormat and the translation check pass

Test results

Full in-app exit on Spark's hosted regtest, at 2a203b4 on an iPhone 17 Pro 2x simulator (iOS 27.0), dark mode, a fresh dev wallet:

• 🟢 Start and funding: a 25,000 sat deposit (24,901 after the claim fee) quoted 20,480 to exit, 9,077 in fees, about 11,403 received, 15,253 of fee funding in 24 parts and 4,421 staying on Spark as balance it can't exit. Fund from another wallet: the faucet paid 15,253 to the funding address, Funding showed Payment seen, and after the swipe Progress showed the funding step done and published the first 7 of 29 transactions, each accepted. Notifications were denied, and Progress shows that note.
• 🟠 Done: running, ~33 h of regtest timelocks. Hosted regtest mines a block about every 31 s and can't be mined on demand, and Progress reads Ready in 23d at mainnet block times (about 3,300 blocks). The app stays open on the simulator, since the simulator has no BGTaskScheduler. This line is updated at Done with the sweep and what reached the destination.

QA of SDK 0.28.0 (comment), at 328b29a on an iOS simulator, local Spark regtest plus one exit on Spark's hosted regtest:

• 🟢 Pay from savings with per-node funding, the partial top-up hints with each extra input's fee, Pay a higher fee (paid and already covered), an evicted fee-change sweep retried at the new floor, a 0.27.2 record resumed on 0.28, a lost race on a per-node funded node, a stale state, Redo with the leftover sweep, the rebuilt-from-chain note, and the hosted fan-out and node packages.
• 🟠 The lone-transaction package retry was not reached: the hosted host now answers /tx with real codes. Unit tests cover it.
• ⏭️ Not covered: the failed cooperative leaf retry and release, the OperatorsUnavailable wait, and the fee-change wait from high network fees. The changes from the independent review are unit-tested only.

QA (earlier):
Tested on an iPhone 17 Pro simulator (iOS 27.0) against Spark's hosted regtest, and on an iPhone 17 Pro simulator (iOS 26.5) against a local Spark regtest stack (QA Notes, Setup).

Device tests skipped ⚠️:

• Background runs: the simulator has no BGTaskScheduler (4).
• Mainnet, a fee-ladder leaf exit and the leftover sweep on a funded run: see Mainnet tests.

Evidence

• Stalls, leaf waits and the other Glow-aligned behaviour at df489ccd: the exit tests and the unit suite (CI's selection) pass on an iPhone 17 Pro simulator (iOS 27.0); SwiftFormat and the translation check pass. Not run on a regtest stack yet.
• One notification for a lost exit, at 5d18a238: the exit tests and the unit tests (CI's selection) pass on an iPhone 16 simulator (iOS 27.0); SwiftFormat passes.
• Fee chain that lost a race, and the dust floor on the needs-funding amount, at 46ae7556: the exit tests and the unit suite (CI's selection) pass on an iPhone 16 simulator (iOS 27.0); SwiftFormat passes.
• Emergency exit fixes from the local regtest runs (result after Done, no double pay, a fresh funding address per exit, keyless timelocks, lost and unexitable leaves, the quote's unexitable amount) at 174d9ed7: the exit tests and the unit suite (CI's selection) pass on an iPhone 17 Pro simulator (iOS 27.0); SwiftFormat and the translation check pass.
• Emergency exit funding, leftover sweep and late value at 022d3ed2: the exit tests and the unit suite pass on an iPhone 17 simulator (iOS 27.0).
• Emergency exit in the background at 335182af: the unit suite and the exit tests pass on an iPhone 17 simulator (iOS 27.0). Against Spark's hosted regtest, the background entry point from a cold start, over a stored exit of 30 steps: keyless pass 1.03 s (7.00 s before status reads ran concurrently), SDK connect 0.03 s (before the SDK's own sync), checkRecoverFunds on one real step 0.55 s (0.17 s warm), one package broadcast to the live node 0.17 s, prepareRecoverFunds 0.55 s, whole run 1.26 s against a 25 s refresh budget; the process footprint grew by about 2 MB (25 to 27 MB, in a test host with no UI).
• Emergency exit at f6d639cb: SparkExitRegtestTests passes against Spark's hosted regtest (empty-wallet quote, chain reads, a live package answer).

Open

• UI polish waiting on design. The new exit screens (Pay a higher fee, the funding split line, the fee-change and cancelled results) are built from existing components; they wait for a design pass.
• Hosted-regtest run. A full exit by a harness on SDK 0.27.2, making the same calls as the app's driver, reached Done on Spark's hosted regtest: all 19 steps confirmed and the sweep confirmed. The app's own full exit there is running (Test results).
• Mainnet exit and fee-ladder leaves. Under Mainnet tests.
• BGTaskScheduler on a real device. The simulator has no BGTaskScheduler, so the OS granting and expiring the exit's tasks is not exercised (4).
• On dev, the Home countdown compares a Spark-chain timelock height with the staging chain's height, so it is wrong there; the progress screen uses Spark's chain.
• The result after Done with its sweep, the fresh funding address, the keyless timelocks and lost or left-behind leaves are covered by unit tests only (7 to 9). A lost or left-behind leaf's value stays in the exit's in-transfer amount until the exit ends.
• An optimization that starts while Spark connects is not seen, since the event listener is added after connect returns, so a quote right after launch does not wait for it.

Mainnet tests (run by the author)

These run on real devices with mainnet funds, by the author. Reviewers and review bots don't need to run them, and they don't block review.

Round 1

• Read-only check on a fresh wallet with nothing funded: Spark connected and synced on https://bitkit.to/electrs, Emergency exit opened up to the quote (Nothing can be exited right now), and the SDK's fee estimate and the exit's chain reads went to https://bitkit.to/electrs only. Nothing was broadcast. On 7220fd0 on a simulator, with debug-only logging (result not posted).

Round 2 (pending)

On the final heads, per the small mainnet exit: a fresh wallet, a low-fee week (about 2 sat/vB) and about 20,000 sats in Savings for the fees.

• Read-only check again on the final head.
• Deposit about 50,000 sats into Spark and wait for it to settle; the quote lists the leaves it moves, what stays on Spark and the total fee.
• Start, with the fees paid from Savings: Home shows the amount in transfer with a countdown, and Spark stops sending and receiving.
• Each step confirms, with packages accepted at https://bitkit.to/electrs, and none is published by the operators first.
• Reminders: a notification when a step needs the app opened, in time for its window of about 50 blocks.
• Restart the app mid-exit: it resumes and nothing is broadcast twice.
• Fee-ladder leaves: their refunds go out and confirm (unit tests only so far).
• The leaves are swept to Savings, Savings gains the exited amount minus the fees, and leftover fee funding returns to Savings.
• The exit screen shows Done, with one completion notification.

Models used

• Planning/scoping: claude-opus-5-5 (reasoning: medium), claude-sonnet-5-5 (reasoning: high)
• Implementation: claude-opus-5-5 (reasoning: medium)
• Review: claude-sonnet-5-5 (reasoning: high)

Taken from the run logs of every session and subagent that planned, wrote or reviewed this PR, which record the model and reasoning effort per turn. The claude-sonnet-5-5 planning runs were research and audit subagents.